TO:	all SAIL users
FROM:	Scott Daniels
RE:	SAIL library

	For some time, there has been talk of trying to create a library
of SAIL routines in order to save programming time on any one project. 
In a recent discussion between members of the SUMEX and IMSSS programming
communities, we decided to try to create such a library. In order to 
encourage use of the library, we felt that it must be reliable, stable, 
well documented, simple to use, and useful to a fairly large community.  
There are already a number of SAIL libraries at IMSSS, but they are, 
in some cases, quite specialized.  What we hope to do is collect many 
commonly used routines, along with as many other general programs as 
possible from the SAIL user community.  

	On the other hand, we realize that the documentation of a program
to library standards involves some extra effort for which we have limited
means of compensation.  In favorable circumstances, this includes:

	a)  Appreciation and recognition by one's colleagues.

	b)  Cataloging and some degree of maintenance.

	c)  Assured availability from a <LIBRARY> directory.

	As an unfiltered collection could readily get out of hand with an
aggregation of redundant or poorly tested programs than might generate
more confusion than value, we are setting a rather strict threshold for
the <LIBRARY> set.  See the further remarks below on <PROGRAM-CATALOG>
for additional levels of communication about useful program sources.

	The model for the SAIL library submission and inclusion process 
will be similar to that of a technical journal.  Specifically, submitted 
programs will be reviewed according to the guidelines given below and 
comments and suggested changes, if any, referred back to the author.
The reviewing and verification process is a vital part of the library, 
since one of the critical needs for the library is that every procedure 
work as advertised (it seems clear that any potential user of the 
library will only use it as long as he is able to rely on the routines 
included).

	We will likely set up several modes of responsibility for
library routines depending on the desires of the author.  In some cases
the author may want sole control over bug fixing, changes, etc.  In
others this responsibility may be delegated to the librarian or shared
jointly.  The library resources available for program maintenance will
be limited so we will have to be selective in the latter cases.  In
any case we will observe strict rules of attribution for contributing
authors as with technical papers.  Upon submission, the author should
include a description of the development of the program with any
appropriate acknowledgements.

	Since we cannot anticipate all of the problems that we will 
encounter when the library gets under way, we are starting with a 
limited community of SAIL users from SUAI, SRI, SUMEX, and IMSSS.  This 
letter is a request for your suggestions, procedures, comments, or 
ideas for the library.  We would especially like to hear reactions to our 
ideas on what procedures should be included, comments on which procedures 
you would like to see in the library, and any suggestions
about how to make the library an effective tool.


REVIEW PROCEDURES

	Every program submitted is to be reviewed by at least two people, 
who will examine the routine for accuracy, and comment upon its
appropriateness for the library.  Referees will be selected from among
the community of active SAIL users.  The librarian will examine the 
routine and coordinate any necessary iterations with the author.  Upon
acceptance, the librarian will place the routine in the library and
distribute it to participating centers.

Functions: 

   Librarian	1) program submission point
		2) complaint center
		3) responsibility for maintenance, updates, etc.
		4) communications center (user-author interfaces)

   Reviewer	1) program verification
		2) documentation examination
		3) initial modifications
		4) possible program improvements


     INFORMATION TO INCLUDE ALONG ANY WITH PROGRAM BEING SUBMITTED
     ----------- -- ------- ----- --- ---- ------- ----- ---------


Suggested program name (six or less characters):
Author(s) and acknowledgements:
How to reach:
Do you wish to be anonymous? (no credits listed):
Do you wish to be unavailable? (no method of reaching listed):

Disposition of non-cosmetic alterations:
	1)  inform author(s) and make any changes 
	2)  request author(s) to make changes
	3)  accept or reject only, no changes
	4)  author doesn't ever want to hear about this program again
				change or throw away...

Bugs encountered(*):
	1)  willing to hear from users
	2)  willing to hear from librarian
	3)  don't want to know

(*) Hopefully this will rarely, if ever, happen.  Every procedure will
    have 2 people verify it before placing it in the library.  If a 
    program fails to perform as documented, it will be fixed.  However,
    if a "bad" program slips in, it may be 
	(a) removed (only if drastic problem), or 
	(b) fixed and renamed (old procedure and name will remain)


HOW TO SUBMIT A PROCEDURE:
--- -- ------ - ----------
a) all submissions must be in a format that can be easily machine read
    (actual file on the SUMEX or IMSSS systems, DEC-tape, or paper tape)

b) submissions should include the procedure, the above information, and
    anything else you feel will help us.

c) Where to submit:
	1) From IMSSS place a copy of the file on <SAILIB>, and SNDMSG 
	   a note to <SCOTT> saying the file is there.

	2) From SUMEX place a copy of the file on <LIBRARY>, and SNDMSG 
	   a note to <DANIELS> saying the file is there.

	3) From SUAI either use the IMSSS linker program to submit as
	   if from IMSSS, use the ARPA net to get to SUMEX, or use 
	   ID-mail to the address below.

	4) From SRI either use the ARPA net to get to SUMEX, or mail to

		   Scott Daniels 
		   Ventura hall, IMSSS,
		   Stanford, California   94305


NOTE: As of the writing of this letter, the ARPA connection to SUMEX 
	is not always operational.  Those users who would normally use 
	the ARPA connection to communicate with us may have to resort 
	to DEC-tape for a while (We will return your tape as soon as 
	we have copied it onto our system).


PROCEDURE DESIGN GUIDELINES:
--------- ------ ----------

1) no large external data structure should be required
2) the procedure should be a single conceptual unit
3) only one assembly switch allowed: "DEC!CODE" which will be true if
	the library is being assembled for a DEC-system, and false if 
	it is being assembled for a TENEX system.
4) the procedure may depend on several library functions, but these 
	should be clearly stated in the documentation, and the list of 
	these (including any further chaining) should be kept to a 
	minimum.
5) no tremendously long argument lists (I suspect it is not conceptually 
	clean if it takes 20 arguments)
6) simple procedures and procedures that return values are encouraged 
7) procedures should somehow process any value thrown to them (if you
	are writing log(x), deal with the -1 case)
8) the standard code comment character will be "!" use it to do 
	code-related comments to help the reviewers verify your program
9) a user-oriented description of the code and a brief abstract should 
	be included (do not necessarily say how the function does what 
	it does here, say what it does and how to use it).  The abstract
	should be oriented to facilitate retrieval of the program
	description by keyword search.
10) the procedure should be useful for more than four or five people
	(let's try and avoid procedure pollution).  These routines will
	hopefully be included in many sail installations, and this is
	not the mechanism for inserting: 
		SIMPLE BOOLEAN PROCEDURE fullmoon( INTEGER date ); 
11) some of the above problems may be corrected by the reviewers, don't
	be frightened out of submitting a program that fails to fit all
	of the above criteria.  The amount of rewriting done or remarks 
	and suggestions made will vary from reviewer to reviewer, however. 
	If you want to be sure that your procedure gets the benefit of
	professional review and is eligible for the library, write and 
	document it carefully.
12) procedure groups are possible (several routines that together share
	information or some non-library procedure).
13) the following words are not to be defined in the procedure :
	"BFAIL", "EFAIL", "BFORT", "EFORT", "BSAIL", "ESAIL", 
	"DECL", "DESR", "ISAIL", or "SSAIL". 
14) Complex programs should include self-documenting help features



	NOTE: all file names here are tentative, the actual names at
		any installation will be decided when the first copy
		of the library material is delivered.

All user access should be read-only except for the files:
	LIBRARY.GRIPE		the obvious...valid complaints and 
					hate mail   (message.txt ?)
	LIBRARY.REQUEST		requests for library functions
	LIBRARY.SUBMISSIONS	source for programs for submission

User access:	4 files that can be "REQUIRE SOURCE!FILE"'d:
			1)	LIBFUN.LIB
			2)	LIBFUN.DCL
			3)	LIBIO.LIB
			4)	LIBIO.DCL

documentation access:	(includes user-oriented documentation, credits, 
			where to find the source code, index...)
			1)	LIBFUN.DOC
			2)	LIBIO.DOC

source code:	
	files that can have pages lifted (for anyone that wants the 
	library functions "almost like, but") to find the source code 
	for a particular procedure, see that procedure's documentation.



<CATALOG>  (Somewhat along the model of DECUS listings)

	Many additional programs may not be ripe for library 
authentication.  We will therefore also maintain a catalog of abstracts 
describing programs that reside on the author's directory but which may 
be available on whatever terms are documented in the abstract.  We may 
also maintain a collection of unverified program sources upon request of 
authors who may be leaving a particular project.  Facility managers will 
take no responsibility for these texts.  At minimum they should be 
self-documenting with respect to whatever further information can be 
obtained about them.